Copyright (c) 1999 Massachusetts Institute of Technology

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, see https://gnu.org/licenses or write
to:
  Free Software Foundation, Inc.
  51 Franklin Street, Fifth Floor
  Boston, MA 02110-1301
  USA
------------------------------

Warning- don't believe everything in this file!


		     ITS NCP INTERFACE

CALL:	.OPEN

	FUNCTION:       OPEN channel to Network

	ARGUMENT TEMPLATE:
		1.  Channel number in AC field of .OPEN instruction
		2.  4 word block addressed by @ E (X) field of 
		    .OPEN instruction
		    4 word block has this form:

	_________________________________________________
	|			|			|
 	|      MODE BITS	|   SIXBIT /NET/	|
	|_______________________|_______________________|
	|						|
	|		  LOCAL SOCKET			|
	|_______________________________________________|
	|						|
	|		 FOREIGN SOCKET			|
	|_______________________________________________|
	|						|
	|			FOREIGN HOST		|
	|_______________________________________________|

    
			   MODE BITS

                                              |--------- don't buffer more
                                              |          output than allocation
                                              |
                                              |   |----- 0-200 words
                                              |   |      1-2000 words
                                              |   |
____________________________________________________________________________
|           |           |           |   |   |out|big|by- lis gen|im-        |
|           |     SIZE OF BYTE      |   |   |ctl|buf| te ten sok|age blk out|
|___________|___________|___________|___|___|___|___|___|___|_#_|___|___|___|
                  |                               |   |   |    |_____|
BYTE SIZE IF      |  0-"NORMAL"                   |   |   |       |
MODE=44	        __|  1-8 BIT BYTE SIZE     _______|   |   |       
(BYTE & IMAGE)	       IF ASCII                       |   |    STANDARD  
		       USE BYTE FIELD                 |   |      ITS
		       IF IMAGE                       |   |     MODES
					              |   |  ______________
		     0-"NORMAL"      	              |   |  |            |
		     1-LISTEN ON           ___________|   |  | 0XX ASCII  |
		       LOCAL SOCKET		          |  | 1XX IMAGE  |
						          |  | X0X UNIT   |
		     0-USE LOCAL 		          |  | X1X BLOCK  |
		       SOCKET FIELD                       |  | XX0 INPUT  |
		     1-GENERATE            _______________|  | XX1 OUTPUT |
		       "UNIQUE" SOCKET                       |____________|
		       # (USE .RCHST
		       TO FIND OUT 
		       RESULT)


		
		LOCAL SOCKET
			32 bit socket # for local identification

		FOREIGN SOCKET
			32 bit socket # determined by foreign host
			system

		FOREIGN HOST
			8 bit socket # specifying computer system
			with which to contact


	RETURNS:	None

	SKIPS:		No Skip If Fails

	FAILURE RETURNS:
		Indicated in LH of .STATUS value (low order 6 bits
		in LH)
		i.e.    .STATUS ch, ac
			LDB ac, [220600,,ac]

		CODE____

		 2	"WRONG DIRECTION"
			(gender of socket wrong for mode)

		 6	"DEVICE FULL"
			(socket table full)

	 	 7	"DEVICE NOT READY"
			(NCP not up, or IMP not up)

		13	"FILE ALREADY EXISTS"
			(socket already open by you on another channel)

		22	"CONTRADICTORY OPEN"
			(byte size mismatched)

		23	"FILE LOCKED"
			(socket number not part of your allocated 
			"unique" group of 8 allocated to your job)

		41	"OTHER END OF PIPELINE GONE OR NOT OPEN"
			(HOST dead or non-existant see NETHST call)


	SIDE EFFECTS:



	EXAMPLES:
		;to listen	.OPEN ch, listen
				JRST fail
				  .
				  .

		Listen:		20,,'NET
				1		;waiting socket
				0		;socket determined when
						 matching RFC received
				0		;host determined when
						 matching RFC received


		:to get "unique socket"
				.OPEN ch, unique
				JRST fail

		:Unique		10,,'NET
				0		;determined by system
				1305		;foreign socket
				6		;foreign host


Equivalent:

	.CALL OPEN

	arg 1	mode,,channel number
	arg 2	SIXBIT/NET/
	arg 3	local socket
	arg 4	foreign socket
	arg 5	host number


CALL:	.RCHST

	FUNCTION:       Read extended STatus of network CHannel

	ARGUMENT TEMPLATE:	AC/ channel,,


	RETURNS:
		WORD	_________________________________
			|		|		|
		 0	|		|     'NET	|
			|_______________|_______________|
			|				|
		 1	|          LOCAL SOCKET		|
			|_______________________________|
			|				|
		 2	|	  FOREIGN SOCKET	|
			|_______________________________|
			|   |		|  BYTE	|	|
		 3	| I | (reserved)|  SIZE |  HOST |
			|___|___________|_______|_______|
			|		|		|
		 4	|   IMP DOWN	|     STATE	|
			|_______________|_______________|
			|		|		|
		 5	|  (reserved)	|      CLS	|
			|_______________|_______________|
			|		|		|
		 6	|  (reserved)	|     #BITS	|
			|_______________|_______________|


		INTERRUPT
			4.9 bit of word 3
			set by receipt over network of INR/INS
			control message (see protocol)
			cleared by .RESET
			causes interrupt on channel

		BYTE SIZE
			9 bit field
			byte size of connection (bits 2.9 - 2.1)
		
		HOST
			9 bit field (8 used by Network foreign host #)

		IMP DOWN
			time in 1/30 sec. until IMP going down 
			(if planned)
			-1  not going down
	 		 0  down
			+n  planned to go down in n/30 sec.
			(see also NETIMP call)


		STATE
			%NSCLS	 0  connection closed
			%NSLSN	 1  listening for RFC
			%NSRFC	 2  RFC in to listen
			%NSRCL	 3  CLS received after RFC
			%NSRFS	 4  RFC sent
			%NSOPN	 5  open
			%NSRFN	 6  RFNM wait on output
			%NSCLW	 7  CLS sent, waiting for matching CLS
			%NSCLI	10  CLS received data available to input
			%NSINP	11  input available


		REASON FOR CLS (state 0)
			%NCNTO	 0  never opened connection (not .OPEN)
			%NCUSR	 1  CLS by user (.CLOSE)
			%NCFRN	 2  CLS by foreign host
			%NCRST	 3  RST (reset) from foreign host (dead)
			%NCDED	 4  host dead (see also NETHST call)
			%NCINC	 5  incomplete transmission (see NETHST)
			%NCBYT	 6  byte size mismatch
			%NCNCP	 7  local NCP went down, breaking connection
			%NCRFS	10  connection refused by foreign host


	SKIPS:		No skip

	FAILURE RETURNS:	None


	SIDE EFFECTS:	None


	EXAMPLE:
			MOVE ac, [ch,,blk]
			.RCHST ac,
			  .
			  .

		BLK:	BLOCK 7

Equivalent:

	.CALL RCHST

	arg 1	network channel number

	val 1	'NET,,0
	val 2	local socket number
	val 3	foreign socket number
	val 4	4.9 interrupt received
		2.1-2.9 byte size
		1.1-1.9 host number
	val 5	LH IMP Down time/reason
		RH Socket state (%NSxxx)
	val 6	Open mode
	val 7	RH Close reason (%NCxxx)
	val 8	RH Number of bits____ available
		   (input data available or output buffer room)


.CALL WHYINT

	arg 1	network channel number

	val 1	%WYNET
	val 2	Socket state (%NSxxx)
	val 3	Number of bytes_____ available
		   (input data available or output buffer room)
	val 4	Close reason (%NSxxx)

This call is usually used to respond to a second-word interrupt
from a network channel.



CALL:	.STATUS

	FUNCTION:       Reads status of Network channel

	ARGUMENT TEMPLATE:
		Channel number in AC field of .STATUS instruction

	RETURNS:	Status of word in location addressed by
			@ E (X) fields of .STATUS instruction

	SKIPS:		No skip


	FAILURE RETURNS:	None

	SIDE EFFECTS:	None

	EXAMPLE:
			.STATUS ch, statwd
		Statwd:	BLOCK 1


		FORMAT OF STATUS WORD

		_________________________________
		|		|		|
		|   ERROR CODE	|    SS0026	|
		|_______________|_______________|


		ERROR CODE
			if IOC (I/O channel error) or OPEN failure,
			codes will be stored here.

		SS
			state (byte 140600), same as that given for
			.RCHST -- see list of states

		26	
			code for Network device


Equivalent:

	.CALL STATUS

	arg 1	channel number

	val 1	status word as above



CALL:	.NETACC

	FUNCTION:       NETwork ACcepts Connection (after LISTEN type
			.OPEN)
			(to REJECT, do a .CLOSE)

	ARGUMENT TEMPLATE:
		Channel number in AC field of .NETACC instruction

	RETURNS:	Nothing

	SKIPS:		Skips on success

	FAILURE RETURNS:
		Not skip --not in state 2 (RFC received to LISTEN)

	SIDE EFFECTS:	Sends matching RFC (and "allocate" if input)

	EXAMPLE:
			.NETACC ch,
			JRST error





CALL:	.NETS

	FUNCTION:       NET Send buffer now
		(Buffer is normally sent when "full" or after
		1/2 second of first activity)

	ARGUMENT TEMPLATE:
		Channel number in AC field .NETS of instruction

	RETURNS:	Nothing

	SKIPS:		No skip

	FAILURE RETURNS:
		IOC (I/O channel error)
		Code 1, if not SEND (write) channel

	SIDE EFFECTS:	Buffer is queued to be sent immediately

	EXAMPLE:
			.NETS ch,


CALL:	.CALL FORCE

	arg 1	channel number

	Equivalent to .NETS (see above)


CALL:	.CALL FLUSH

	arg 1	channel number

	Does FORCE then waits for all buffered data to be sent
	and for the final RFNM to come back.


CALL:	.CLOSE

	FUNCTION:       CLOSEs channel and returns immediately

	ARGUMENT TEMPLATE:
		Channel number in AC field of .CLOSE instruction

	RETURNS:	None

	SKIPS:		No skip

	FAILURE RETURNS:	None

	EXAMPLE:
			.CLOSE ch,


Equivalent:

	.CALL CLOSE

	arg 1	channel number


CALL:	.CALL NETBLK

	FUNCTION:       Hang until connection is not in specified
		state or until time out 

	ARGUMENT TEMPLATE:
		Standard .CALL arguments
		1.  channel number
		2.  state -- returns when not in this state
		3.  (optional) time -- number of 30ths of second
		    to wait or -- (time since system up) in 30ths
		    of second

	RETURNS:	1.  (optional) state -- new state
			2.  (optional) time -- time left after state
			    change

	SKIPS:		Skips on success

	FAILURE RETURNS:
		Not skip and
		OPEN code 14 -- channel number not <20
		-- channel not Network device

	SIDE EFFECTS:	None

	EXAMPLE:
				.CALL netblk
				JRST error
			  	  .
			  	  .

		Netblk:		SETZ
				SIXBIT /NETBLK/
				channel
				state
				time
				2000,,newstate
				402000,,timeleft

		Channel:	ch
	
		State:		<-wait for this state to be left>-

		Time:		<-30ths of second to wait>-

		Newstate:	BLOCK 1

		Timeleft:	BLOCK 1


	The time argument is clobbered in the same way that
	.SLEEP clobbers its AC; unless it is immediate.  In that
	case, the time out will be restarted if the job is pclsred.


CALL:	.RESET

	FUNCTION:       Used to RESET interrupt bit
		(INR/INS from Network)

	ARGUMENT TEMPLATE:
		Channel number in AC field of .RESET instruction

	RETURNS:	Nothing

	SKIPS:		No skip

	FAILURE RETURNS:	None

	SIDE EFFECTS:	Clears the Network interrupt bit (see .RCHST,
		bit 4.9 of word 3)

	EXAMPLE:
			.RESET ch,

Equivalent:

	.CALL RESET

	arg 1	channel number



CALL:	.NETINT

	FUNCTION:       Sends Network INR/INS control message for
		link corresponding to channel.  (TELNET protocol also 
		demands a "data mark" to be inserted in the stream)

	ARGUMENT TEMPLATE:
		Channel number in AC field of .NETINT instruction

	RETURNS:	Nothing

	SKIPS:		Skip if success
			No skip if Network down or not a Network
			channel

	FAILURE RETURNS:	
		I/O Channel error Interrupt, NET went down
		Code 1

	SIDE EFFECTS:	Sends NET INR/INS control message

	EXAMPLE:
			.NETINT ch,
			JRST fail




CALL:	.GETSYS areas
		NCPHTB
		NCPPQ
		NCPSM

	FUNCTION:       Get socket map
			host table
			pending queue

	ARGUMENT TEMPLATE:
		Name of first of 2 consecutive accumulators in AC
		field of .GETSYS instruction

		ac/	-<-length>-,,<-address>-    ;CPTR to block to store

		ac+1/	SIXBIT/<-name>-/	;sixbit name of area
						 desired


	RETURNS:	Block of desired information

	SKIPS:		Skips on success

	FAILURE RETURNS:
		No skip -- area name not known in system -- not
		enough memory
		(ac+1 zeroes)
		(ac gets <-lng,,> for number of words needed)

	SIDE EFFECTS:	None

	EXAMPLE 1:
		;This can be used to find out how much storage is
		 needed for a .GETSYS block

				HRROI ac,temp
				MOVE ac+1, [SIXBIT/NCPSM/]
				.GETSYS ac,
				HLRES ac		;here ac contains
							 lng,,temp
				MOVNS ac		;now ac contains
							 number of words
							 needed
				CALL FREE (ac)


	EXAMPLE 2:
				MOVE ac, [-lng,,blk]
				MOVE ac+1 [SIXBIT /NCPSM/]
						or NCPHTB or NCPPQ
				.GETSYS ac,
				JRST error
				  .
				  .

		BLK:		BLOCK lng



NCPHTB area

	Length -- 400 (8) words (256(10))

	Format -- one word per host number
		(word(i) is data for host.number (i))

	Each word has info packed --
	
	|1|      | 2 |    9    |       18   
	______________________________________________
	|R|      |   |         |  |                  |
	|F|      |   |         |  |                  |
	|N|unused|RST| CTL TIME|00| HOST DEAD STATUS |
	|M|      |   |         |  |                  |
	|_|______|___|_________|__|__________________|


	RFNM	0-control link open
		1-waiting for RFNM on control link

	RST	0-host down or not tried
		1-sent RST to see if up
		2-got RRP, connections may be opened

	CTL TIME			    9
		Last time (1/30 sec module 2 )
		message sent to this host on control link (0)

	HOST DEAD STATUS
		Last HOST DEAD STATUS from this host's IMP
		(See RFC 611)

(If data for a single host is desired, use the NETHST call)

	HOST DEAD STATUS in right half

	Bits 20-31	(byte pointer [041400,,x])
			give the time of the Host's coming back up,
			bit-coded as follows:


	Bits 20-22	(byte pointer [150300,,x]
			the day of the week the Host is coming back up
			Monday is day 0 and Sunday is day 6

	Bits 23-27	(byte pointer [100500,,x])
			the hour of the day, from hour 0 to hour 23,
			that the Host is coming back up

	Bits 28-31	(byte pointer [040400,,x])
			the five minute interval, from 0 to 11, in the
			hour that the Host is coming back up


	All three of the above are specified in Universal Time
	(i.e., G.M.T.).  The Host may indicate that it will be
	coming back up more than a week away by setting bits 20-31
	all to ones (7777).  Setting all bits 20-30 to one and bit
	31 to zero (20-31 = 7776) means it is unknown when the Host
	is coming back up. 

Bits 32-35 have the follwing meanings:

          Value  Meaning
          -----  -------

          0    The destination Host is not communicating with the
               network -- the destination IMP has no information
               about the cause.  Note that this is the message most
               likely to occur if the destination IMP has gone down
               since the destination Host went down.

          1    The destination Host is not communicating with the
               network -- it took its ready-line down without saying
               why.

          2    The destination Host is not communicating with the
               network -- the Host was tardy in taking traffic from
               the network and the network had to declare the Host
               down.

          3    The destination Host does not exist to the knowledge
               of the NCC.

          4    Currently unused.

          5    The destination Host is down for scheduled P.M.

          6    The destination Host is down for scheduled hardware
               work.

          7    The destination Host is down for scheduled software
               work.

          8    The destination Host is down for emergency restart.

          9    The destination Host is down because of power outage.

          10   The destination Host is stopped at a software
               breakpoint.

          11   The destination Host is down because of a hardware
               failure.

          12-15 Currently Unused.

     When the value of this 4-bit field is 0,1,2, or 3, bits 20-31
will have the "unknown" indication.
NCPPQ area -- pending queue of RFC's

	Length -- variable 3+4*n where n is currently 40 (8) but
		  may change

	Format -- 
		word 0 -- relocation word, tells location in system
		core where first slot begins

		word 1 -- pointer to first queue entry

		word 2 thru 4*n+1 -- 4 word slot for queue or -1 if
			last one on queue
		     (0) -- pointer to next one (must un-relocate, 
			    using word 0
		     (1) -- local socket number
		     (2) -- foreign socket number
		     (3) -- sign bit 0 = STR  1 = RTS
			    low order 8 bits (byte pointer [001000,,X])
			    link number if RTS
			    byte size if STR
			    next 8 bits (byte pointer [101000,,x])
			    foreign Host number


Example of unrelocating for the NCPPQ area.
	;Let ac,ac+1 and b be accumulators

		MOVE ac, [-lng,,blk]
		MOVE ac+1, [SIXBIT /NCPPQ/]
		GETSYS ac,
		JRST error
		MOVEI ac, blk
		MOVN b,(ac)			;-system address
	loop:	ADD ac,b			;ac now points to
						;first queue entry

			;0(ac) is next pointer word
			;1(ac) is local socket word
			;2(ac) is foreign socket word
			;3(ac) is Host -- lind/byte word

		MOVE ac,0(ac)			;get next
		JUMPGE ac,loop			;loop if not last one

NCPSM area

	Length -- 1+13.*20. = 261(10) or 405(8)
		  there are 13 (or more) blocks each of length
		  IMPSTL (an assebly parameter, currintly 20(n))

	Format -- 
		  word 0 -- contains IMPSTL, the number of words
			    in each block
		  word 1 -- begins first block -- the blocks are:

IMSOC1:	REPEAT IMPSTL,0		; 0 => FREE
				; 4.9 = 1 => SOCKET IN USE
				; 4.8 = 1 => CHNL TRYING TO BE CLOSED
				; 3.1-4.7 MASK FOR INTERRUPT BIT (LSH 1 CHNL#)
				; RH = USER INDEX
IMSOC2:	BLOCK IMPSTL		; 1.1-4.5 = LOCAL SOCKET NUMBER
				; 4.6-4.9  0 (MAKES COMPARISONS EASIER)
IMSOC3:	BLOCK IMPSTL		; 1.1-4.5 = FOREIGN SOCKET NUMBER
				; 4.6-4.9 = 0
IMSOC4:	BLOCK IMPSTL		; RH = SOCKET STATE
				; 3.1-3.8 = LINK NUMBER
				; 3.9-4.7 = FOREIGN HOST NUMBER
				; 4.8 = SET BY RCV CLS - MAKES MATCH USING IMSCHD FAIL
				; 4.9 = SEND THIS BUFFER NOW
IMSOC5:	BLOCK IMPSTL		; 1.1-1.8 = CONNECTION BYTE SIZE
				; 2.1-2.9 = CLOSE REASON
				; 3.1-3.8 = USER BYTE SIZE
				; 3.9 => ASCII MODE - 7 BIT
				; 4.1 => ASCII MODE - 8 BIT
				; 4.2 => 1 BIT BYTES
				; 4.3 => NET INTERRUPT (INR/INS) RECEIVED
				; 4.4 => HAVE BEGUN CLOSE TIMEOUT
				; 4.5 => CLOSED WHILE IN RFNM WAIT, EXPECT ANOTHER RFNM
				; 4.9 => TRANSFER IN 32 BIT MODE
IMSOC6:	BLOCK IMPSTL		; RH => BUFFER ADDRESS
				; 4.9 => LOCKED BY CORE JOB
				; 4.8 => ACTIVE AT PI LEVEL
				; 4.7 => INPUT OCCURRED WHILE BUFFER LOCKED
				; 3.1-3.8 => IOBFT INDEX, OR 377 IF BIG BUFFER
IMSOC7:	BLOCK IMPSTL		; BIT ALLOCATION
IMSOC8:	BLOCK IMPSTL		; MESSAGE ALLOCATION
IMSC7I:	BLOCK IMPSTL		; AMOUNT TO INCREASE BIT ALLOCATION BY IN NEXT ALL MSG
IMSC8I:	BLOCK IMPSTL		; AMOUNT TO INCREASE MESSAGE ALLOCATION BY " " " "
IMSOCT:	BLOCK IMPSTL		; TIME WHEN FIRST MESS PUT INTO BUF
				; (DURING INPUT HAS NUMBER OF DATA BYTES LEFT IN MSG)
				; (DURING CLOSE HAS TIME TIMEOUT STARTED)
IMSMPP:	BLOCK IMPSTL		; MAIN PROGRAM POINTER, ILDB OR IDPB FOR NEXT BYTE
IMSMPC:	BLOCK IMPSTL		; MAIN PROGRAM COUNTER, FOR OUTPUT HAS ROOM LEFT
				; IN BUFFER IN BYTES.  FOR INPUT HAS TOTAL NUMBER
				; OF DATA BYTES IN THE BUFFER.
IMSPIP:	BLOCK IMPSTL		; INTERRUPT LEVEL POINTER.  FOR OUTPUT ILDB GETS
				; FIRST BYTE OF NEXT MESSAGE OUT.  FOR INPUT RH
				; HAS ADDRESS OF HEADER WORD OF NEXT MESSAGE IN.
IMSBFE:	BLOCK IMPSTL		; BYTE POINTER TO LAST BYTE IN BUFFER.

CALL:	.IOT

	FUNCTION:	Transfer data in or out over Network

	ARGUMENT TEMPLATE:
		Channel number in AC field of .IOT in struction
		<-word>- or pointer to block

	RETURNS:	None (unit output mode)
			Datum (unit input mode)
			Updated pointer (block mode)

	SKIPS:		No skip

	FAILURE RETURNS:
		I/O Channel error INTERRUPT
		Code 1 -- Network went down
		Code 8 -- Attempted output mode IOT when not in
			  State 5 (open) or State 6 (RFNM wait)
			  Or attempted input IOT when in bad state
			  or when closed other than by foreign host.
		End of file is sensed when input is done from
		a socket closed by the foreign host.  In unit
		image mode this gives I/O channel error code 2.

	SIDE EFFECTS:
		Output -- data buffered to be sent
		Input  -- data copied from buffer ALLOCATE sent if
			  buffer empty (enough)

	EXAMPLE:	.IOT ch, foo


In image block mode, one byte per word is transferred,
right-justified.

In ascii block mode, five bytes per word are transferred,
or four bytes per word (8-bit) if mode bit 1.6 was on in
the OPEN.

